<div class="content">

  <h1>Migrating to 5.0.0</h1>

  <section class="toc">
    <ul>
      <li><a simplePageScroll href="#section-builders">Builders all the way down</a></li>
      <li><a simplePageScroll href="#section-why-builders">Why builders?</a></li>
      <li><a simplePageScroll href="#section-what-changed">So what API changed?</a></li>
      <li><a simplePageScroll href="#section-conditional-config">Conditional config?</a></li>
      <li><a simplePageScroll href="#section-spring-support">Changes to Spring support</a></li>
      <li><a simplePageScroll href="#section-transportstrategy-renamed">TransportStrategy renamed</a></li>
      <li><a simplePageScroll href="#section-libraries-unshaded">Libraries DKIM and email-rfc2822-validator not included in the JAR anymore</a></li>
    </ul>
  </section>

  <a href="#section-builders" id="section-builders" class="section-link h2">&sect;</a>
  <h2>Builders all the way down</h2>

  <section>
    <p class="wide">
      With all the possible ways to configure Email and Mailer instances, the library had only one option left to streamline API, avoid the
      <a href="http://codethataint.com/blog/telescoping-constructor-pattern-java/">Telescoping Constructor</a> anti-pattern and keep things
      managable: <a href="https://martinfowler.com/bliki/FluentInterface.html">fluent builders</a>.
    </p>
  </section>

  <a href="#section-why-builders" id="section-why-builders" class="section-link h2">&sect;</a>
  <h2>Why builders?</h2>

  <section>
    <div class="wide">
      <ol class="indent">
        <li>With fluent builders, we can tightly control <strong>valid combinations</strong>, logical <strong>decision paths</strong> and easily <strong>provide
          alternative methods</strong>.
        </li>
        <li>At the same time we can move all the mutation logic to the builders and produce mostly <strong>immutable objects</strong>.</li>
        <li>Finally, we're now able to <strong>centralize our documentation</strong> around the builders and refer to it from wherever it is used.</li>
      </ol>
    </div>
  </section>

  <a href="#section-what-changed" id="section-what-changed" class="section-link h2">&sect;</a>
  <h2>So what API changed?</h2>

  <section>
    <div class="view">
      <p>All the constructors and mutation methods of <code class="inline">Mailer</code> have been replaced by the
        <code class="inline">MailerBuilder</code>.<br/>
        Similarly, all the constructors and mutation methods of <code class="inline">Email</code> have been replaced by the
        <code class="inline">EmailBuilder</code>.</p>
    </div>
    <div class="side">
      <pre><code>// So instead of:
Email email = new Email();
email.setFromAddress(...)

// you start with EmailBuilder instead:
Email email = EmailBuilder.startingFromBlank()
        .from(...)
        .buildEmail();
      </code></pre>
      <pre><code>// And instead of:
Mailer mailer = new Mailer(/*...many options...*/);
mailer.setDebug(true);

// you start with MailerBuilder instead:
Mailer mailer = MailerBuilder.
        //.manyOptions()
        .withDebugLogging(true)
        .buildMailer();
      </code></pre>
    </div>
  </section>

  <section>
    <div class="view">
      <p>
        Furthermore all the reading methods on Mailer have been consolidated into <strong>parameter
        objects</strong> and made available where previously not yet disclosed.
      </p>
    </div>
    <div class="side">
      <pre><code>// For example, to read out the thread pool size:
Mailer mailer = ...;
int poolsize = mailer.getOperationalConfig().getThreadPoolSize();
</code></pre>
      The following information is available to you now:
      <pre><code>email.getAnythingYouCanSetWithABuilder();

mailer.getSession(); // the only mutable object
mailer.getTransportStrategy();
mailer.getServerConfig();
mailer.getProxyConfig();
mailer.getOperationalConfig();
mailer.getEmailAddressCriteria();
</code></pre>
    </div>
  </section>

  <a href="#section-conditional-config" id="section-conditional-config" class="section-link h2">&sect;</a>
  <h2>Conditional configuration</h2>

  <section>
    <div class="view">
      <p>Here's a simple example of conditional configuration using builders</p>
    </div>
    <div class="side">
      <pre><code class="small">MailerRegularBuilder builder = MailerBuilder.withSMTPServer("smtp.host.com", 25);

if (yourCondition) {{ '{' }}
    builder.withSMTPServerPort(26);
    builder.withTransportModeLoggingOnly(false);
{{ '}' }}

Mailer mailer = builder.buildMailer();
</code></pre>
    </div>
  </section>

  <a href="#section-spring-support" id="section-spring-support" class="section-link h2">&sect;</a>
  <h2>Changes to Spring support</h2>

  <section>
    <p class="wide">
      The Java configuration has not changed, but Spring beans in XML configuration is not supported anymore out-of-the-box.
    </p>
    <p class="wide">
      This is because there are no constructors or bean setters/getters anymore, which you would normally use to create a Spring bean in XML.
      The only way around this for XML configuration, is to provide your own builder method and refer to that from your bean xml so you can utilize the new builder API.
    </p>
    <p class="wide">
      Refer to the <a simplePageScroll [routerLink]="['/configuration']" href="#section-spring-support">configuration section</a>
      to see some current Spring examples
    </p>
  </section>

  <a href="#section-transportstrategy-renamed" id="section-transportstrategy-renamed" class="section-link h2">&sect;</a>
  <h2>TransportStrategy renamed</h2>

  <section>
    <div class="view">
      <p>
        Due to security updates
        <a href="https://github.com/bbottema/simple-java-mail/issues/105">#105</a> and
        <a href="https://github.com/bbottema/simple-java-mail/issues/111">#111</a> a rename of the TransportStrategy enum was in order.
      </p>
      <p>
        This is because there are not more constructors or bean setters to use when creating a Spring bean in XML.
        The only way around this for XML configuration, is to provide your own builder method and refer to that from your bean xml.
      </p>
    </div>
    <div class="side">
      For v4, here are the possible values:
      <pre><code class="language-properties">simplejavamail.transportstrategy=SMTP_PLAIN
simplejavamail.transportstrategy=SMTP_SSL
simplejavamail.transportstrategy=SMTP_TLS</code></pre>
      For v5, the following will work:
      <pre><code class="language-properties">simplejavamail.transportstrategy=SMTP
simplejavamail.transportstrategy=SMTPS
simplejavamail.transportstrategy=SMTP_TLS</code></pre>
    </div>
  </section>

  <a href="#section-libraries-unshaded" id="section-libraries-unshaded" class="section-link h2">&sect;</a>
  <h2>Libraries DKIM and email-validator not included in the JAR anymore</h2>

  <section>
    <div class="view">
      <p>
        Due to issues with updating
        (<a href="https://github.com/bbottema/simple-java-mail/issues/120">#120</a>) and downloading sources
        (<a href="https://github.com/bbottema/simple-java-mail/issues/122">#122</a>) for the externals libraries DKIM and email-rfc2822-validator,
        these dependencies are not included in the generated Simple Java Mail JAR anymore.
      </p>
      <p>
        Instead, they are now included and updated like regular Maven dependencies again.
      </p>
      <p>
        <strong>Note that the DKIM library is optional and only loaded when using the DKIM API, but email-rfc2822-validator is (still) included by default.</strong>
      </p>
    </div>
    <div class="side">
      To include the DKIM library:
      <pre><code class="language-xml">&lt;dependency&gt;
    &lt;groupId&gt;net.markenwerk&lt;/groupId&gt;
    &lt;artifactId&gt;utils-mail-dkim&lt;/artifactId&gt;
    &lt;version&gt;X.X.X&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
      email-rfc2822-validator is included by default, but you can update the version as follows:
      <pre><code class="language-xml">&lt;dependency&gt;
    &lt;groupId&gt;com.github.bbottema&lt;/groupId&gt;
    &lt;artifactId&gt;emailaddress-rfc2822&lt;/artifactId&gt;
    &lt;version&gt;X.X.X&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
    </div>
  </section>
</div>
